<!DOCTYPE html>
<html>
<head>
<title>JSON-LD Requirements</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<script type="text/javascript" src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>

<script type="text/javascript" class="remove">
   var respecConfig = {
      // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
      specStatus:           "CG-FINAL",
      //publishDate:          "2011-07-13",
      
     // the specification's short name, as in https://www.w3.org/TR/short-name/
      shortName:            "json-ld-requirements",
      subtitle:             "A Context-based JSON Serialization for Linked Data",
      // if you wish the publication date to be other than today, set this
      // publishDate:  "2009-08-06",

      // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
      // and its maturity status
      //previousPublishDate:  "2011-07-13",
      //previousMaturity:     "ED",
      //previousDiffURI:      "https://json-ld.org/requirements/ED/20110713/index.html",
      //diffTool:             "https://www.aptest.com/standards/htmldiff/htmldiff.pl",

      // if there a publicly available Editor's Draft, this is the link
      edDraftURI:           "https://json-ld.org/requirements/latest/",
      includePermalinks:      true,
      noRecTrack:             true,

      // if this is a LCWD, uncomment and set the end of its review period
      // lcEnd: "2009-08-05",

      // editors, add as many as you like
      // only "name" is required
      editors:  [
          { name: "Gregg Kellogg", url: "https://greggkellogg.net/",
            company: "Kellogg Associates" },
      ],

      github:    "https://github.com/json-ld/json-ld.org",
      // authors, add as many as you like. 
      // This is optional, uncomment if you have authors as well as editors.
      // only "name" is required. Same format as editors.

      // name of the WG
      wg:           "JSON for Linking Data W3C Community Group",
      
      // URI of the public WG page
      wgURI:        "https://www.w3.org/community/json-ld/",
      
      // name (with the @w3c.org) of the public mailing to which comments are due
      wgPublicList: "public-linked-json",
      
      // URI of the patent status for this WG, for Rec-track documents
      // !!!! IMPORTANT !!!!
      // This is important for Rec-track documents, do not copy a patent URI from a random
      // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
      // Team Contact.
      maxTocLevel: 3,
      //alternateFormats: [ {uri: "diff-20110507.html", label: "diff to previous version"} ],
  };
  </script>
  <style>
  .diff { font-weight:bold; color:#0a3; }
  </style>
</head>

<body>
<section id="abstract">
<p>
  This document attempts to gather requirements for Linked Data in JSON (JSON-LD)
  in order to create an objective measure with which to evaluate the
  <cite><a href="/spec/latest/">JSON-LD Specification</a></cite>.
</p>
</section>

<section id='sotd'>
<p>This document is an experimental work in progress.</p>
<!-- <p>
This document has been reviewed by W3C Members, by software
developers, and by other W3C groups and interested parties, and is
endorsed by the Director as a W3C Recommendation. It is a stable
document and may be used as reference material or cited from another
document. W3C's role in making the Recommendation is to draw attention
to the specification and to promote its widespread deployment. This
enhances the functionality and interoperability of the Web.
</p> -->
</section>

<section>
<h1>Introduction</h1>
</section>

<section><h1>Definitions</h1>
  <dl>
    <dt><dfn>JSON</dfn></dt><dd>
      <abbr title="JavaScript Object Notation">JSON</abbr> (JavaScript Object Notation)
      [[!RFC4627]]
      is a simple way to express objects in a syntax compatible with JavaScript.
    </dd>
    <dt>Linked Data</dt><dd>
      Linked Data is a term used to describe data relationships through interconnected documents. The
      basic tenets are described in the [[LINKED-DATA]] design note by Tim Berners-Lee:
      <ol data-cite="LinkedData">
        <li>
          <p>
            Use <small>URI</small>s as names for things
          </p>
        </li>
        <li>
          <p>
            Use <small>HTTP</small> <small>URI</small>s so that
            people can look up those names.
          </p>
        </li>
        <li>
          <p>
            When someone looks up a <small>URI</small>, provide useful information.
          </p>
        </li>
        <li>
          <p>
            Include links to other <small>URIs</small> so that they
            can discover more things.
          </p>
        </li>
      </ol>
    </dd>
    <dt>Structured Data</dt><dd>
      Structured Data describes general means of describing inter-relationships between entities in a way that can be
      described using a graph or tree structure. JSON is an example of a grammar for describing Structured Data. In
      the context of JSON-LD, Structured Data refers to <a>JSON object</a>s in which the subject may not have an IRI, or
      where the IRI is not dereferencable, or does not retrieve a representation of the object to which it refers.
    </dd>
    <dt><dfn>JSON Object</dfn></dt><dd>
      From [[RFC4627]]: <blockquote data-cite="RFC4627">
        An object structure is represented as a pair of curly brackets surrounding zero or
        more name/value pairs (or members). A name is a string. A single colon comes after
        each name, separating the name from the value. A single comma separates a value
        from a following name. The names within an object SHOULD be unique.
      </blockquote>
    </dd>
  </dl>
</section>

<section><h1>Requirements</h1>
  <section><h2>Linked Data</h2>
    <p>
      The following are taken to be assertions about the meaning of <a>Linked Data</a>.
    </p>
    <p class="note">
      This section is intended to abstractly describe the concept of <a>Linked
      Data</a>. This does not necessarily relate concepts directly to a JSON syntactic
      expression; that is left for the following section.
    </p>
    <ol>
      <li><dfn>Linked Data</dfn> is a set of documents, each containing a representation of a linked data graph.</li>
      <li>A <dfn>linked data graph</dfn> is an unordered labeled directed graph, where nodes are <a>subject</a>s or <a>object</a>s, and edges are properties.</li>
      <li>A <dfn>subject</dfn> is any node in a <a>linked data graph</a> with at least one outgoing edge.</li>
      <li>A <a>subject</a> SHOULD be labeled with an IRI.</li>
      <li>A <dfn>property</dfn> is an edge of the <a>linked data graph</a>.</li>
      <li>A <a>property</a> SHOULD be labeled with an IRI.</li>
      <li>An <dfn>object</dfn> is a node in a <a>linked data graph</a> with at least one incoming edge.</li>
      <li>An <a>object</a> MAY be labeled with an IRI.</li>
      <li>An IRI that is a label in a <a>linked data graph</a> SHOULD be dereferencable to a <a>Linked Data</a> document describing the labeled <a>subject</a>, <a>object</a> or <a>property</a>.</li>
      <li>A <dfn>literal</dfn> is an <a>object</a> with a label that is not an IRI</li>
    </ol>
  </section>
  <section><h2>Structured Data</h2>
    <p>
      Definitions for Linked Data are often stricter than is required for many applications, where it is not feasible
      or desirable to identify every object with an IRI which resolves to a <a>Linked Data</a> representation
      of the IRI used to reference it. In such cases, graphs may be described with unlabeled nodes, or nodes having
      non-dereferencable IRIs.
    </p>
    <p>
      <dfn>Structured Data</dfn> is described as a super-set of <a>Linked Data</a> in which <a>subject</a> or <a>object</a> nodes are not labeled with a dereferencable IRI. The concept of
      a <a>linked data graph</a> is extended to include nodes in which nodes are not labeled with dereferencable IRIs.
    </p>
  </section>
  <section><h2>JSON-LD</h2>
    <p>The following are taken to be requirements and principles for creating <a>Linked Data</a> in JSON.</p>
    <ol>
      <li>A JSON-LD document MUST be able to express a <a>linked data graph</a>.</li>
      <li>A JSON-LD document MUST be a valid JSON document.</li>
      <li>
        All JSON constructs MUST have semantic meaning in a
        JSON-LD document: <a>JSON object</a>s, arrays, numbers, strings and the literal
        names false, and true.
      </li>
      <li>A <a>subject</a> is defined using a designated name/value pair of a <a>JSON object</a>.</li>
      <li>There MUST be a way to label a <a>JSON object</a> with an IRI.</li>
      <li>There MAY be a way to reference an un-labeled JSON object that does not have a direct child relationship.</li>
      <li><a>JSON object</a> name/value SHOULD be used to describe <a>property</a>-<a>object</a> relationships.</li>
      <li>A <a>property</a> SHOULD resolve to an absolute IRI.</li>
      <li>Un-coerced strings represent literal <a>object</a>s.</li>
      <li>Coerced strings MAY represent IRIs.</li>
      <li>There SHOULD be a way to associate a datatype IRI with a literal JSON value.</li>
      <li>JSON boolean and numbers values represent specific datatyped literals.</li>
      <li>The literal value of JSON null is undefined.</li>
      <li>A JSON array MAY be used to associate multiple <a>object</a>s with a <a>subject</a> through a common <a>property</a>.</li>
      <li>Without explicit syntactic support, JSON arrays MUST NOT be interpreted as defining an object ordering.</li>
      <li>A JSON-LD document SHOULD be able to express an ordered list of objects.</li>
    </ol>
  </section>
</section>

</body>
</html>

